<!--This is the page used to describe HKGolden API-->
<!--Author: GraphiteCube-->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
        <meta name="viewport" content="width=device-width" />
        <title>HKGolden Express | API</title>
        <link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./favicon.ico" />
        <link rel="stylesheet" type="text/css" href="Styles/Common.css" />
        <link rel="stylesheet" type="text/css" href="Styles/Api.css" />
    </head>

    <body>
        <!--HKGolden Express title-->
        <div class="HKGoldenExpressTitle">
            <a href="index.jsp">HKGolden Express</a>
            <hr />
        </div>

        <!--Introduction section-->
        <div>
            <h3>Introduction</h3>
            <p>
                Disclaimer: Use this document at your own risk.
                This HKGolden API documentation is not provided by HKGolden.
                Do not use this document if you want 100 percent correct documentation.
                Contact HKGolden if you want to know the exact details of HKGolden API.
            </p>
            <p>
                This page describes the HKGolden API.
                HKGolden API can be accessed by sending a HTTP request with required parameters.
                XML document or JSON data will be sent back to client as response.
                Right now there are 4 kinds of services which can be accessed through HKGolden API:
                Get topics, get message content, submit new message/ reply to message and search for topics.
            </p>
            <p>
                Note: The XML document provided by HKGolden API is not standards-compliant,
                and it cannot be parsed by JDom and DocumentBuilder (XML parsers for Java) correctly.
                It is caused by incorrect encoding attribute in the XML declaration.
            </p>
            <p>
                Note: On 22<sup>nd</sup> March, 2010, the encoding of XML document changed from Big5 to UTF-8,
                however the encoding attribute in the XML declaration is still incorrect.
            </p>
            <p>
                Note: Sometimes the XML document returned from HKGolden API contains invalid XML character
                (most of the invalid characters are found in author names). To solve this problem,
                you may want to change the XML version of the XML document from 1.0 to 1.1.
                This solution is applied on HKGolden Express (Build 201004181455) and is proved to work.
                However, this solution is not 100 percent reliable and may make XML parser behave weirdly.
            </p>
        </div>
        <hr />

        <!--Section to describe how to get topics through HKGolden API-->
        <div>
            <h3>Get Topics</h3>
            <p>To get the topics on HKGolden forum, send the following HTTP GET request:</p>
            <div class="Code">
                http://api.hkgolden.com/topics.aspx?returntype=RETURN_TYPE&amp;page=PAGE_NUMBER&amp;pagesize=TOPICS_AMOUNT&amp;type=CHANNEL
            </div>
            <br />
            <ul>
                <li>
                    RETURN_TYPE: The format of data.
                    Possible values are "xml" (XML document) or "json" (JSON data).
                </li>
                <li>PAGE_NUMBER: The page number.</li>
                <li>TOPICS_AMOUNT: The number of topics to be included in XML document returned.</li>
                <li>CHANNEL: The channel of HKGolden forum. For example, BW represents "吹水台".</li>
            </ul>
        </div>
        <hr />

        <!--Section to describe how to get message content through HKGolden API-->
        <div>
            <h3>Get Message Content</h3>
            <p>To get the message content of a message on HKGolden forum, send the following HTTP GET request:</p>
            <div class="Code">
                http://api.hkgolden.com/view.aspx?returntype=RETURN_TYPE&amp;message=MESSAGE_ID&amp;start=START_IDX&amp;end=END_IDX
            </div>
            <br />
            <ul>
                <li>
                    RETURN_TYPE: The format of data.
                    Possible values are "xml" (XML document) or "json" (JSON data).
                </li>
                <li>MESSAGE_ID: The message ID.</li>
                <li>START_IDX: The index of reply to start fetching.</li>
                <li>END_IDX: The index of last reply to get.</li>
            </ul>
            <p>
                Notice: No matter the value of START_ID,
                the message body of first message (message by thread starter) is always included.
            </p>
        </div>
        <hr />

        <!--Section to describe how to get message quote through HKGolden web service-->
        <div>
            <h3>Get Message Quote</h3>
            <p>Get message quote of a reply message, send the following HTTP POST request:</p>
            <div class="Code">
                http://forum2.hkgolden.com/MessageFunc.asmx/quote_message
            </div>
            <br />
            <p>Parameters:</p>
            <ul>
                <li>s_MessageID: The message ID.</li>
                <li>
                    s_ReplyID: The reply ID, which is the value of <span class="Code">Reply_ID</span> in JSON string returned from getting message content through HKGolden API.
                </li>
            </ul>
            <p>
                Note: You must send the parameters using JSON format; you will send the parameters and their values in following pattern:<br /><br />
                <span class="Code">{'s_MessageID':MID,'s_ReplyID':RID}</span><br /><br />
                Substitute <span class="Code">MID</span> and <span class="Code">RID</span> with appropiate value.
            </p>
            <p>
                Note: You must set the <span class="Code">Content-Type</span> in request header as <span class="Code">application/json; charset=utf-8</span>,
                otherwise the HKGolden server will redirect you to homepage of HKGolden.
            </p>
        </div>
        <hr />

        <!--Section to describe how to post new message or reply to a message through HKGolden API-->
        <div>
            <h3>Post New Message/ Reply</h3>
            <p>To post a new message or reply to a message, send the following HTTP POST request:</p>
            <div class="Code">
                http://api.hkgolden.com/post.aspx
            </div>
            <br />
            <p>Parameters:</p>
            <ul>
                <li>username: E-mail address of HKGolden account.</li>
                <li>pass: Password of HKGolden account.</li>
                <li>ipaddr: IP address of client who post new message or reply to a message.</li>
                <li>ft: The channel of HKGolden forum. For example, BW represents "吹水台".</li>
                <li>title: The title of new message. Not required if replying to a message.</li>
                <li>body: The message body.</li>
                <li>
                    returntype: The format of result data.
                    Possible values are "xml" (XML document) or "json" (JSON data).
                </li>
                <li>mt: Indicate if replying a message (value should be "Y") or posting new message (value should be "N").</li>
                <li>id: The message ID of message to reply to (value should be "0" for posting new message).</li>
            </ul>
            <p>
                Note: The values of title and body must be encoded in Big5 encoding.
            </p>
        </div>
        <hr />

        <!--Section to describe how to search for topics through HKGolden API-->
        <div>
            <h3>Search For Topics</h3>
            <p>To search for topics, send the following HTTP GET request:</p>
            <div class="Code">
                http://api.hkgolden.com/search.aspx?returntype=RETURN_TYPE&amp;searchstring=SEARCH_STRING&amp;st=SEARCH_TYPE
            </div>
            <br />
            <ul>
                <li>
                    RETURN_TYPE: The format of data.
                    Possible values are "xml" (XML document) or "json" (JSON data).
                </li>
                <li>SEARCH_STRING: The search string.</li>
                <li>SEARCH_TYPE: The search type. Possible values are "T" (title) or "A" (author name).</li>
            </ul>
        </div>
        <hr />

        <!--Section to describe other unknown API/ web services provided by HKGolden-->
        <div>
            <h3>Unknown APIs/ Web Services</h3>
            <p>There are other APIs or web services provided by HKGolden:</p>
            <ul>
                <li>
                    Bookmark Alert Web Services:<br />
                    <span class="Code">
                        http://forum2.hkgolden.com/golden_apps/bb_bmalert/bmalertFunctions.asmx
                    </span>
                </li>
                <li>
                    Bookmark Web Services:<br />
                    <span class="Code">
                        http://forum2.hkgolden.com/golden_apps/bb_bookmark/bmFunctions.asmx
                    </span>
                </li>
                <li>
                    Message Web Services:<br />
                    <span class="Code">
                        http://forum2.hkgolden.com/MessageFunc.asmx
                    </span>
                </li>
            </ul>
            <p>
                Since there is no official API reference from HKGolden,
                you may need to spend some time on finding out how to use other APIs/ web services.
            </p>
        </div>
        <hr />

        <!--HKGolden Express title-->
        <div class="HKGoldenExpressTitle">
            <a href="index.jsp">HKGolden Express</a>
        </div>
    </body>
</html>